<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>Module: Sass</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <meta http-equiv="Content-Script-Type" content="text/javascript" />
  <link rel="stylesheet" href=".././rdoc-style.css" type="text/css" media="screen" />
  <script type="text/javascript">
  // <![CDATA[

  function popupCode( url ) {
    window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400")
  }

  function toggleCode( id ) {
    if ( document.getElementById )
      elem = document.getElementById( id );
    else if ( document.all )
      elem = eval( "document.all." + id );
    else
      return false;

    elemStyle = elem.style;
    
    if ( elemStyle.display != "block" ) {
      elemStyle.display = "block"
    } else {
      elemStyle.display = "none"
    }

    return true;
  }
  
  // Make codeblocks hidden by default
  document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" )
  
  // ]]>
  </script>

</head>
<body>



    <div id="classHeader">
        <table class="header-table">
        <tr class="top-aligned-row">
          <td><strong>Module</strong></td>
          <td class="class-name-in-header">Sass</td>
        </tr>
        <tr class="top-aligned-row">
            <td><strong>In:</strong></td>
            <td>
                <a href="../files/vendor/plugins/haml/lib/sass/constant_rb.html">
                vendor/plugins/haml/lib/sass/constant.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass/css_rb.html">
                vendor/plugins/haml/lib/sass/css.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass/engine_rb.html">
                vendor/plugins/haml/lib/sass/engine.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass/error_rb.html">
                vendor/plugins/haml/lib/sass/error.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass/plugin_rb.html">
                vendor/plugins/haml/lib/sass/plugin.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass/tree/node_rb.html">
                vendor/plugins/haml/lib/sass/tree/node.rb
                </a>
        <br />
                <a href="../files/vendor/plugins/haml/lib/sass_rb.html">
                vendor/plugins/haml/lib/sass.rb
                </a>
        <br />
            </td>
        </tr>

        </table>
    </div>
  <!-- banner header -->

  <div id="bodyContent">



  <div id="contextContent">

    <div id="description">
      <h1><a href="Sass.html">Sass</a> (Syntactically Awesome StyleSheets)</h1>
<p>
<a href="Sass.html">Sass</a> is a meta-language on top of <a
href="Sass/CSS.html">CSS</a> that&#8216;s used to describe the style of a
document cleanly and structurally, with more power than flat <a
href="Sass/CSS.html">CSS</a> allows. <a href="Sass.html">Sass</a> both
provides a simpler, more elegant syntax for <a href="Sass/CSS.html">CSS</a>
and implements various features that are useful for creating manageable
stylesheets.
</p>
<h2>Features</h2>
<ul>
<li>Whitespace active

</li>
<li>Well-formatted output

</li>
<li>Elegant input

</li>
<li>Feature-rich

</li>
</ul>
<h2>Using <a href="Sass.html">Sass</a></h2>
<p>
<a href="Sass.html">Sass</a> can be used in two ways: As a plugin for Ruby
on Rails and as a standalone parser. <a href="Sass.html">Sass</a> is
bundled with <a href="Haml.html">Haml</a>, so if the <a
href="Haml.html">Haml</a> plugin or RubyGem is installed, <a
href="Sass.html">Sass</a> will already be installed as a plugin or gem,
respectively.
</p>
<p>
To install <a href="Haml.html">Haml</a> and <a href="Sass.html">Sass</a> as
a Ruby on Rails plugin, use the normal Rails plugin installer:
</p>
<pre>
  ./script/plugin install http://svn.hamptoncatlin.com/haml/tags/stable
</pre>
<p>
<a href="Sass.html">Sass</a> templates in Rails don&#8216;t quite function
in the same way as views, because they don&#8216;t contain dynamic content,
and so only need to be compiled when the template file has been updated. By
default (see options, below), &quot;.sass&quot; files are placed in
public/stylesheets/sass. Then, whenever necessary, they&#8216;re compiled
into corresponding <a href="Sass/CSS.html">CSS</a> files in
public/stylesheets. For instance, public/stylesheets/sass/main.sass would
be compiled to public/stylesheets/main.css.
</p>
<p>
Using <a href="Sass.html">Sass</a> in Ruby code is very simple. First
install the <a href="Haml.html">Haml</a>/<a href="Sass.html">Sass</a>
RubyGem:
</p>
<pre>
  gem install haml
</pre>
<p>
Then you can use it by including the &quot;sass&quot; gem and using <a
href="Sass/Engine.html">Sass::Engine</a> like so:
</p>
<pre>
  engine = Sass::Engine.new(&quot;#main\n  :background-color #0000ff&quot;)
  engine.render #=&gt; &quot;#main { background-color: #0000ff; }\n&quot;
</pre>
<h2><a href="Sass/CSS.html">CSS</a> Rules</h2>
<p>
Rules in flat <a href="Sass/CSS.html">CSS</a> have two elements: the
selector (e.g. &quot;main&quot;, &quot;div p&quot;, &quot;li a:hover&quot;)
and the attributes (e.g. &quot;color: 00ff00;&quot;, &quot;width:
5em;&quot;).
</p>
<p>
<a href="Sass.html">Sass</a> has both of these, as well as one additional
element: nested rules.
</p>
<h3>Rules and Selectors</h3>
<p>
However, some of the syntax is a little different. The syntax for selectors
is the same, but instead of using brackets to delineate the attributes that
belong to a particular rule, <a href="Sass.html">Sass</a> uses two spaces
of indentation. For example:
</p>
<pre>
  #main p
    &lt;attribute&gt;
    &lt;attribute&gt;
    ...
</pre>
<h3>Attributes</h3>
<p>
There are two different ways to write <a href="Sass/CSS.html">CSS</a>
attrbibutes. The first is very similar to the how you&#8216;re used to
writing them: with a colon between the name and the value. However, <a
href="Sass.html">Sass</a> attributes don&#8216;t have semicolons at the
end; each attribute is on its own line, so they aren&#8216;t necessary. For
example:
</p>
<pre>
  #main p
    color: #00ff00
    width: 97%
</pre>
<p>
is compiled to:
</p>
<pre>
  #main p {
    color: #00ff00;
    width: 97% }
</pre>
<p>
The second syntax for attributes is slightly different. The colon is at the
beginning of the attribute, rather than between the name and the value, so
it&#8216;s easier to tell what elements are attributes just by glancing at
them. For example:
</p>
<pre>
  #main p
    :color #00ff00
    :width 97%
</pre>
<p>
is compiled to:
</p>
<pre>
  #main p {
    color: #00ff00;
    width: 97% }
</pre>
<h3>Nested Rules</h3>
<p>
Rules can also be nested within each other. This signifies that the inner
rule&#8216;s selector is a child of the outer selector. For example:
</p>
<pre>
  #main p
    :color #00ff00
    :width 97%

    .redbox
      :background-color #ff0000
      :color #000000
</pre>
<p>
is compiled to:
</p>
<pre>
  #main p {
    color: #00ff00;
    width: 97%; }
    #main p .redbox {
      background-color: #ff0000;
      color: #000000; }
</pre>
<p>
This makes insanely complicated <a href="Sass/CSS.html">CSS</a> layouts
with lots of nested selectors very simple:
</p>
<pre>
  #main
    :width 97%

    p, div
      :font-size 2em
      a
        :font-weight bold

    pre
      :font-size 3em
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    width: 97%; }
    #main p, #main div {
      font-size: 2em; }
      #main p a, #main div a {
        font-weight: bold; }
    #main pre {
      font-size: 3em; }
</pre>
<h3>Referencing Parent Rules</h3>
<p>
In addition to the default behavior of inserting the parent selector as a
<a href="Sass/CSS.html">CSS</a> parent of the current selector (e.g. above,
&quot;main&quot; is the parent of &quot;p&quot;), you can have more
fine-grained control over what&#8216;s done with the parent selector by
using the ampersand character &quot;&amp;&quot; in your selectors.
</p>
<p>
The ampersand is automatically replaced by the parent selector, instead of
having it prepended. This allows you to cleanly create pseudo-attributes:
</p>
<pre>
  a
    :font-weight bold
    :text-decoration none
    &amp;:hover
      :text-decoration underline
    &amp;:visited
      :font-weight normal
</pre>
<p>
Which would become:
</p>
<pre>
  a {
    font-weight: bold;
    text-decoration: none; }
    a:hover {
      text-decoration: underline; }
    a:visited {
      font-weight: normal; }
</pre>
<p>
It also allows you to add selectors at the base of the hierarchy, which can
be useuful for targeting certain styles to certain browsers:
</p>
<pre>
  #main
    :width 90%
    #sidebar
      :float left
      :margin-left 20%
      .ie6 &amp;
        :margin-left 40%
</pre>
<p>
Which would become:
</p>
<pre>
  #main {
    width: 90%; }
    #main #sidebar {
      float: left;
      margin-left: 20%; }
      .ie6 #main #sidebar {
        margin-left: 40%; }
</pre>
<h3>Attribute Namespaces</h3>
<p>
<a href="Sass/CSS.html">CSS</a> has quite a few attributes that are in
&quot;namespaces;&quot; for instance, &quot;font-family,&quot;
&quot;font-size,&quot; and &quot;font-weight&quot; are all in the
&quot;font&quot; namespace. In <a href="Sass/CSS.html">CSS</a>, if you want
to set a bunch of attributes in the same namespace, you have to type it out
each time. <a href="Sass.html">Sass</a> offers a shortcut for this: just
write the namespace one, then indent each of the sub-attributes within it.
For example:
</p>
<pre>
  .funky
    :font
      :family fantasy
      :size 30em
      :weight bold
</pre>
<p>
is compiled to:
</p>
<pre>
  .funky {
    font-family: fantasy;
    font-size: 30em;
    font-weight: bold; }
</pre>
<h2>Constants</h2>
<p>
<a href="Sass.html">Sass</a> has support for setting document-wide
constants. They&#8216;re set using an exclamation mark followed by the
name, an equals sign, and the value. An attribute can then be set to the
value of a constant by following it with another equals sign. For example:
</p>
<pre>
  !main_color = #00ff00

  #main
    :color = !main_color
    :p
      :background-color = !main_color
      :color #000000
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    color: #00ff00; }
    #main p {
      background-color: #00ff00;
      color: #000000; }
</pre>
<h3>Arithmetic</h3>
<p>
You can even do basic arithmetic with constants. <a
href="Sass.html">Sass</a> recognizes numbers, colors, lengths (numbers with
units), and strings (everything that&#8216;s not one of the above), and
various operators that work on various values. All the normal arithmetic
operators (+, -, *, /, %, and parentheses for grouping) are defined as
usual for numbers, colors, and lengths. The &quot;+&quot; operator is also
defined for Strings as the concatenation operator. For example:
</p>
<pre>
  !main_width = 10
  !unit1 = em
  !unit2 = px
  !bg_color = #a5f39e

  #main
    :background-color = !bg_color
    p
      :background-color = !bg_color + #202020
      :width = !main_width + !unit1
    img.thumb
      :width = (!main_width + 15) + !unit2
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    background-color: #a5f39e; }
    #main p {
      background-color: #c5ffbe;
      width: 10em; }
    #main img.thumb {
      width: 25em; }
</pre>
<h3>Colors</h3>
<p>
Colors may be written as three- or six-digit hex numbers prefixed by a
pound sign (#), or as HTML4 color names. For example, &quot;ff0&quot;,
&quot;ffff00&quot; and &quot;yellow&quot; all refer to the same color.
</p>
<p>
Not only can arithmetic be done between colors and other colors, but it can
be done between colors and normal numbers. In this case, the operation is
done piecewise one each of the Red, Green, and Blue components of the
color. For example:
</p>
<pre>
  !main_color = #a5f39e

  #main
    :background-color = !main_color
    p
      :background-color = !main_color + 32
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    background-color: #a5f39e; }
    #main p {
      background-color: #c5ffbe; }
</pre>
<h3>Strings</h3>
<p>
Strings are the type that&#8216;s used by default when an element in a bit
of constant arithmetic isn&#8216;t recognized as another type of constant.
However, they can also be created explicitly be wrapping a section of code
with quotation marks. Inside the quotation marks, a backslash can be used
to escape quotation marks that you want to appear in the <a
href="Sass/CSS.html">CSS</a>. For example:
</p>
<pre>
  !content = &quot;Hello, \&quot;Hubert\&quot; Bean.&quot;

  #main
    :content = &quot;string(&quot; + !content + &quot;)&quot;
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    content: string(Hello, &quot;Hubert&quot; Bean.) }
</pre>
<h3>Default Concatenation</h3>
<p>
All those plusses and quotes for concatenating strings can get pretty
messy, though. Most of the time, if you want to concatenate stuff, you just
want individual values with spaces in between them. Thus, in <a
href="Sass.html">Sass</a>, when two values are next to each other without
an operator, they&#8216;re simply joined with a space. For example:
</p>
<pre>
  !font_family = &quot;sans-serif&quot;
  !main_font_size = 1em

  #main
    :font
      :family = !font_family
      :size = !main_font_size
    h6
      :font = italic &quot;small-caps&quot; bold (!main_font_size + 0.1em) !font_family
</pre>
<p>
is compiled to:
</p>
<pre>
  #main {
    font-family: sans-serif;
    font-size: 1em; }
    #main h6 {
      font: italic small-caps bold 1.1em sans-serif; }
</pre>
<h2>Directives</h2>
<p>
Directives allow the author to directly issue instructions to the <a
href="Sass.html">Sass</a> compiler. They&#8216;re prefixed with an at sign,
&quot;<tt>@</tt>&quot;, followed by the name of the directive, a space, and
any arguments to it - just like <a href="Sass/CSS.html">CSS</a> directives.
For example:
</p>
<pre>
  @import red.sass
</pre>
<h3>Import</h3>
<p>
Currently, the only directive is the &quot;import&quot; directive. It works
in a very similar way to the <a href="Sass/CSS.html">CSS</a> import
directive, and sometimes compiles to a literal <a
href="Sass/CSS.html">CSS</a> &quot;@import&quot;.
</p>
<p>
<a href="Sass.html">Sass</a> can import either other <a
href="Sass.html">Sass</a> files or plain <a href="Sass/CSS.html">CSS</a>
files. If it imports a <a href="Sass.html">Sass</a> file, not only are the
rules from that file included, but all constants in that file are made
available in the current file.
</p>
<p>
<a href="Sass.html">Sass</a> looks for other <a href="Sass.html">Sass</a>
files in the working directory, and the <a href="Sass.html">Sass</a> file
directory under Rails. Additional search directories may be specified using
the :load_paths option (see below).
</p>
<p>
<a href="Sass.html">Sass</a> can also import plain <a
href="Sass/CSS.html">CSS</a> files. In this case, it doesn&#8216;t
literally include the content of the files; rather, it uses the built-in <a
href="Sass/CSS.html">CSS</a> &quot;@import&quot; directive to tell the
client program to import the files.
</p>
<p>
The import directive can take either a full filename or a filename without
an extension. If an extension isn&#8216;t provided, <a
href="Sass.html">Sass</a> will try to find a <a href="Sass.html">Sass</a>
file with the given basename in the load paths, and, failing that, will
assume a relevant <a href="Sass/CSS.html">CSS</a> file will be available.
</p>
<p>
For example,
</p>
<pre>
  @import foo.sass
</pre>
<p>
would compile to
</p>
<pre>
  .foo
    :color #f00
</pre>
<p>
whereas
</p>
<pre>
  @import foo.css
</pre>
<p>
would compile to
</p>
<pre>
  @import foo.css
</pre>
<p>
Finally,
</p>
<pre>
 @import foo
</pre>
<p>
might compile to either, depending on whether a file called
&quot;foo.sass&quot; existed.
</p>
<h2>Comments</h2>
<h3>Silent Comments</h3>
<p>
It&#8216;s simple to add &quot;silent&quot; comments, which don&#8216;t
output anything to the <a href="Sass/CSS.html">CSS</a> document, to a <a
href="Sass.html">Sass</a> document. Simply use the familiar C-style
notation for a one-line comment, &quot;//&quot;, at the normal indentation
level and all text following it won&#8216;t be output. For example:
</p>
<pre>
  // A very awesome rule.
  #awesome.rule
    // An equally awesome attribute.
    :awesomeness very
</pre>
<p>
becomes
</p>
<pre>
  #awesome.rule {
    awesomeness: very; }
</pre>
<h3>Loud Comments</h3>
<p>
&quot;Loud&quot; comments are just as easy as silent ones. These comments
output to the document as <a href="Sass/CSS.html">CSS</a> comments, and
thus use the same opening sequence: &quot;/*&quot;. For example:
</p>
<pre>
  /* A very awesome rule.
  #awesome.rule
    /* An equally awesome attribute.
    :awesomeness very
</pre>
<p>
becomes
</p>
<pre>
  /* A very awesome rule. */
  #awesome.rule {
    /* An equally awesome attribute. */
    awesomeness: very; }
</pre>
<h2>Output Style</h2>
<p>
Although the default <a href="Sass/CSS.html">CSS</a> style that <a
href="Sass.html">Sass</a> outputs is very nice, and reflects the structure
of the document in a similar way that <a href="Sass.html">Sass</a> does,
sometimes it&#8216;s good to have other formats available.
</p>
<p>
<a href="Sass.html">Sass</a> allows you to choose between three different
output styles by setting the <tt>:style</tt> option. In Rails, this is done
by setting <tt><a
href="Sass/Plugin.html#M000052">Sass::Plugin.options</a>[:style]</tt>;
outside Rails, it&#8216;s done by passing an options hash with
&lt;/tt&gt;:style&lt;/tt&gt; set.
</p>
<h3><tt>:nested</tt></h3>
<p>
Nested style is the default <a href="Sass.html">Sass</a> style, because it
reflects the structure of the document in much the same way <a
href="Sass.html">Sass</a> does. Each attribute has its own line, but the
indentation isn&#8216;t constant. Each rule is indented based on how deeply
it&#8216;s nested. For example:
</p>
<pre>
  #main {
    color: #fff;
    background-color: #000; }
    #main p {
      width: 10em; }

  .huge {
    font-size: 10em;
    font-weight: bold;
    text-decoration: underline; }
</pre>
<p>
Nested style is very useful when looking at large <a
href="Sass/CSS.html">CSS</a> files for the same reason <a
href="Sass.html">Sass</a> is useful for making them: it allows you to very
easily grasp the structure of the file without actually reading anything.
</p>
<h3><tt>:expanded</tt></h3>
<p>
Expanded is the typical human-made <a href="Sass/CSS.html">CSS</a> style,
with each attribute and rule taking up one line. Attributes are indented
within the rules, but the rules aren&#8216;t indented in any special way.
For example:
</p>
<pre>
  #main {
    color: #fff;
    background-color: #000;
  }
  #main p {
    width: 10em;
  }

  .huge {
    font-size: 10em;
    font-weight: bold;
    text-decoration: underline;
  }
</pre>
<h3><tt>:compact</tt></h3>
<p>
Compact style, as the name would imply, takes up less space than Nested or
Expanded. However, it&#8216;s also harder to read. Each <a
href="Sass/CSS.html">CSS</a> rule takes up only one line, with every
attribute defined on that line. Nested rules are placed next to each other
with no newline, while groups of rules have newlines between them. For
example:
</p>
<pre>
  #main { color: #fff; background-color: #000; }
  #main p { width: 10em; }

  .huge { font-size: 10em; font-weight: bold; text-decoration: underline; }
</pre>
<h2><a href="Sass.html">Sass</a> Options</h2>
<p>
Options can be set by setting the hash <tt><a
href="Sass/Plugin.html#M000052">Sass::Plugin.options</a></tt> from
<tt>environment.rb</tt> in Rails, or by passing an options hash to <a
href="Sass/Engine.html">Sass::Engine</a>. Available options are:
</p>
<dl>
<dt><tt>:style</tt></dt><dd>Sets the style of the <a href="Sass/CSS.html">CSS</a> output. See the
section on Output Style, above.

</dd>
<dt><tt>:always_update</tt></dt><dd>Whether the <a href="Sass/CSS.html">CSS</a> files should be updated every
time a controller is accessed, as opposed to only when the template has
been modified. Defaults to false. Only has meaning within Ruby on Rails.

</dd>
<dt><tt>:always_check</tt></dt><dd>Whether a <a href="Sass.html">Sass</a> template should be checked for
updates every time a controller is accessed, as opposed to only when the
Rails server starts. If a <a href="Sass.html">Sass</a> template has been
updated, it will be recompiled and will overwrite the corresponding <a
href="Sass/CSS.html">CSS</a> file. Defaults to false if Rails is running in
production mode, true otherwise. Only has meaning within Ruby on Rails.

</dd>
<dt><tt>:template_location</tt></dt><dd>The directory where <a href="Sass.html">Sass</a> templates should be read
from. Defaults to <tt>RAILS_ROOT +
&quot;/public/stylesheets/sass&quot;</tt>. Only has meaning within Ruby on
Rails.

</dd>
<dt><tt>:css_location</tt></dt><dd>The directory where <a href="Sass/CSS.html">CSS</a> output should be
written to. Defaults to <tt>RAILS_ROOT +
&quot;/public/stylesheets&quot;</tt>. Only has meaning within Ruby on
Rails.

</dd>
<dt><tt>:filename</tt></dt><dd>The filename of the file being rendered. This is used solely for reporting
errors, and is automatically set when using Rails.

</dd>
<dt><tt>:load_paths</tt></dt><dd>An array of filesystem paths which should be searched for <a
href="Sass.html">Sass</a> templates imported with the &quot;@import&quot;
directive. This defaults to the working directory and, in Rails, whatever
<tt>:template_location</tt> is (by default <tt>RAILS_ROOT +
&quot;/public/stylesheets/sass&quot;</tt>).

</dd>
</dl>

    </div>


   </div>


  </div>


    <!-- if includes -->

    <div id="section">

    <div id="class-list">
      <h3 class="section-bar">Classes and Modules</h3>

      Module <a href="Sass/Plugin.html" class="link">Sass::Plugin</a><br />
Module <a href="Sass/Tree.html" class="link">Sass::Tree</a><br />
Class <a href="Sass/CSS.html" class="link">Sass::CSS</a><br />
Class <a href="Sass/Engine.html" class="link">Sass::Engine</a><br />
Class <a href="Sass/SyntaxError.html" class="link">Sass::SyntaxError</a><br />

    </div>




      


    <!-- if method_list -->


  </div>


<div id="validator-badges">
  <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p>
</div>

</body>
</html>